home *** CD-ROM | disk | FTP | other *** search
/ PsL Monthly 1993 December / PSL Monthly Shareware CD-ROM (December 1993).iso / prgmming / dos / c / onkey.exe / ONKEY.TXT < prev   
Text File  |  1994-10-27  |  9KB  |  306 lines
  1.                                    ONKEY
  2.  
  3.  
  4.    This ZIP file contains the following members :
  5.  
  6.    ONKEY.H   - An include file that prototypes the various functions in 
  7.                ONKEY.LIB and #defines various key codes.
  8.     
  9.    ONKEY.LIB - A LARGE Model Library of 'C' functions described below
  10.  
  11.  
  12.    The functions in ONKEY.LIB are described in detail below. The functions
  13.    in this Library are compiled foe the large model and a 286 or better
  14.    processor.
  15.  
  16.    int OnKey(key_code,(function)());
  17.  
  18.    int key_code;        scan code, ascii code of key (see onkey.h)
  19.    void (function)();           function to call when key is pressed
  20.  
  21.    Description.
  22.    
  23.    After a successful call to this function whenever the key described by
  24.    key_code is pressed the associated function is invoked. Passing a function
  25.    of NULL causes the key to be treated as normal.
  26.    The include file onkey.h contains examples of the key codes for some keys.
  27.    The key codes are made up of the scan code and the ascii character and
  28.    represent the value returned by the BIOS INT 16H function 10H call.
  29.  
  30.    Example.
  31.  
  32.    void ProcFN1(void);    
  33.    void ProcFNA1(void);    
  34.  
  35.    main( )
  36.    {
  37.  
  38.      OnKey(F1,ProcFN1);         // call ProcFN1 whenever F1 is pressed
  39.      OnKey(ALT_F1,ProcFNA1); // call ProcFNA1 whenever ALT F1 is pressed
  40.  
  41.      InKey(0);            // wait for a key to be pressed
  42.      OnKey(F1,NULL);        // treat F1 as a normal key
  43.    }    
  44.    ProcFN1( )
  45.    {
  46.       Printf("FN1 Was Pressed\n");
  47.    }    
  48.    ProcFNA1( )
  49.    {
  50.       Printf("FNA1 Was Pressed\n");
  51.    }    
  52.  
  53.    Return Value.
  54.  
  55.    returns 0 if works, -1 if fails. THe only reason to fail is lack of memory.    
  56.     
  57.  
  58.    The example above uses InKey( ) to retrieve a key. The OnKey( ) function
  59.    actually hooks into INT 16H and will invoke the correspnding function
  60.    regardless of what C function you use to get keyboard input.
  61.    Please be aware though that C does stack checking and it is very possible
  62.    that you will get a run time error. i.e the following code will give a
  63.    stack overflow message :
  64.  
  65.  
  66.    void ProcFN1(void);    
  67.    void ProcFNA1(void);    
  68.  
  69.    main( )
  70.    {
  71.  
  72.      int num;
  73.     
  74.      OnKey(F1,ProcFN1);         // call ProcFN1 whenever F1 is pressed
  75.      OnKey(ALT_F1,ProcFNA1); // call ProcFNA1 whenever ALT F1 is pressed
  76.  
  77.      printf("Please enter a number : ");
  78.      scanf("%d",&num);
  79.     
  80.      OnKey(F1,NULL);        // treat F1 as a normal key
  81.    }    
  82.    ProcFN1( )
  83.    {
  84.       Printf("FN1 Was Pressed\n");
  85.    }    
  86.    ProcFNA1( )
  87.    {
  88.       Printf("FNA1 Was Pressed\n");
  89.    }    
  90.  
  91.    Pressing F1 or ALT F1 will cause a stack overflow message to be generated.
  92.    Compiling your program with stack checking disabled (/Gs) will not help in
  93.    the above example because printf already has stack checking embedded within
  94.    it. You have three options to prevent this from happening.
  95.  
  96.    1. Only use the Onkey( ) function in combination with Inkey( ).
  97.  
  98.    2. Compile your programs with the /Gs option and don't use any supplied
  99.       C library routines in the invoked function.
  100.  
  101.    3. Write your own keyboard routine that uses BIOS and not DOS.
  102.      
  103.    The /Gs option is used with the Microsoft C compiler. I assume that other
  104.    C Compilers have a similar option.
  105.  
  106.    int OnKeyCancel(void);
  107.  
  108.    Description.
  109.    
  110.    Cancels all active Onkey( ) calls. You would use this before spawning in
  111.    overlay mode another executeable. This call makes sure that all interrupts
  112.    that the onkey( ) has 'hooked' into are reset.        
  113.  
  114.    Example.
  115.  
  116.    void ProcFN1(void);    
  117.    void ProcFNA1(void);    
  118.  
  119.    main( )
  120.    {
  121.  
  122.      OnKey(F1,ProcFN1);         // call ProcFN1 whenever F1 is pressed
  123.      OnKey(ALT_F1,ProcFNA1); // call ProcFNA1 whenever ALT F1 is pressed
  124.  
  125.      InKey(0);            // wait for a key to be pressed
  126.      OnKeyCancel( );        // Reset all keys to noraml
  127.  
  128.    }    
  129.    ProcFN1( )
  130.    {
  131.       Printf("FN1 Was Pressed\n");
  132.    }    
  133.    ProcFNA1( )
  134.    {
  135.       Printf("FNA1 Was Pressed\n");
  136.    }    
  137.  
  138.    Return Value.
  139.  
  140.    returns 0 if works, -1 if fails. 
  141.  
  142.  
  143.    int InKey(delay);
  144.  
  145.    int delay;    
  146.  
  147.    Description.
  148.        
  149.    Inkey waits delay seconds for a key to be pressed before returning to
  150.    the calling program. A delay value of 0 causes inkey( ) to wait
  151.    until a key is actually pressed. 
  152.  
  153.    Example.
  154.  
  155.  
  156.    main( )
  157.    {
  158.      int key;
  159.     
  160.      key = InKey(0);            // wait for a key to be pressed
  161.  
  162.      key = Inkey(5);                // wait 5 seconds for a key to be pressed
  163.  
  164.  
  165.    }    
  166.  
  167.    Return Value.
  168.    
  169.    returns 0 if no key was pressed within the specified delay time otherwise
  170.    it returns the scan code + ascii character of the key pressed. (See ONKEY.H
  171.    for the values;
  172.  
  173.  
  174.    int LastKey(void);
  175.  
  176.    Description.
  177.        
  178.    Returns the scan code, ascii character of the last key pressed. This function
  179.    only works if a successful Onkey or an Inkey( ) call has been made.     
  180.  
  181.    Example.
  182.  
  183.  
  184.    main( )
  185.    {
  186.      int key;
  187.     
  188.      key = InKey(0);            // wait for a key to be pressed
  189.      ....
  190.      ..
  191.      ..
  192.      ..
  193.      if ( LastKey( ) == HOME)
  194.        {
  195.        .....
  196.        }
  197.    }    
  198.  
  199.    Return Value.
  200.    
  201.    returns the scan code, ascii character of the last key pressed.
  202.  
  203.  
  204.  
  205.    int PutKey(key_code);
  206.  
  207.    int key_code;              // scan code, ascii character to 'stuff'
  208.  
  209.    Description.
  210.            
  211.    This function 'stuffs' the passed keystroke into the keyboard buffer.
  212.    See ONKEY.H for some valid key_codes.
  213.    This function may not work on some older machines. 
  214.  
  215.    Example.
  216.  
  217.  
  218.    main( )
  219.    {
  220.  
  221.      int key;
  222.     
  223.      OnKey(F1,ProcF1);              // hot key F1    
  224.      key = InKey(0);            // wait for a key to be pressed
  225.      if ( lastkey( ) == ENTER)
  226.        printf("Enter was Pressed\n");
  227.    }    
  228.    ProcF1( )
  229.    {
  230.       PutKey(ENTER);                // put an enter key in the buffer      
  231.    }
  232.  
  233.    pressing either F1 or Enter will cause the 'Enter was pressed' message
  234.    to be displayed.
  235.  
  236.    Return Value.
  237.    
  238.    returns -1 if the keyboard buffer is full else returns 0
  239.  
  240.  
  241.    To use these functions in your programs compile them as follows :
  242.  
  243.  
  244.    CL /AL /G2s /c xxxxx.c
  245.    link    xxxxx,,, onkey;
  246.  
  247.    or
  248.  
  249.    cl /AL /G2s xxxxx.c /link onkey
  250.  
  251.    These functions are provided as is, you use them at your own risk. If
  252.    you have any questions or would like source or librarys for other
  253.    memory models please contact me at the CIS mail address below. 
  254.  
  255.    Steve Bridges.
  256.    CIS 71507,1033 
  257.  
  258.          ----------------end-of-author's-documentation---------------
  259.  
  260.                          Software Library Information:
  261.  
  262.                     This disk copy provided as a service of
  263.  
  264.                            Public (software) Library
  265.  
  266.          We are not the authors of this program, nor are we associated
  267.          with the author in any way other than as a distributor of the
  268.          program in accordance with the author's terms of distribution.
  269.  
  270.          Please direct shareware payments and specific questions about
  271.          this program to the author of the program, whose name appears
  272.          elsewhere in  this documentation. If you have trouble getting
  273.          in touch with the author,  we will do whatever we can to help
  274.          you with your questions. All programs have been tested and do
  275.          run.  To report problems,  please use the form that is in the
  276.          file PROBLEM.DOC on many of our disks or in other written for-
  277.          mat with screen printouts, if possible.  PsL cannot debug pro-
  278.          programs over the telephone, though we can answer questions.
  279.  
  280.          Disks in the PsL are updated  monthly,  so if you did not get
  281.          this disk directly from the PsL, you should be aware that the
  282.          files in this set may no longer be the current versions. Also,
  283.          if you got this disk from another vendor and are having prob-
  284.          lems,  be aware that  some files may have become corrupted or
  285.          lost by that vendor. Get a current, working disk from PsL.
  286.  
  287.          For a copy of the latest monthly software library newsletter
  288.          and a li